/*
 * Copyright (C) 2011 JiangHongTiao
 *
 * This program is free software: you can redistribute it and/or modify
 * it under the terms of the GNU General Public License as published by
 * the Free Software Foundation, either version 3 of the License, or
 * (at your option) any later version.
 *
 * This program is distributed in the hope that it will be useful,
 * but WITHOUT ANY WARRANTY; without even the implied warranty of
 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
 * GNU General Public License for more details.
 *
 * You should have received a copy of the GNU General Public License
 * along with this program.  If not, see <http://www.gnu.org/licenses/>.
 */
package sk.lieskove.jianghongtiao.multithreaddownloader.request.params;

import sk.lieskove.jianghongtiao.multithreaddownloader.request.converter.Converter;

import java.io.UnsupportedEncodingException;

/**
 * Param is common interface for parameters which are required by services. All
 * parameters have to be in some format, so {@link sk.lieskove.jianghongtiao.aresapi.webservice.converters.Converter}
 * insure that this parameter is in correct format. 
 * 
 * Date of create: May 19, 2011
 *
 * @author JiangHongTiao <jjurco.sk_gmail.com>
 * @version 2011.0519
 */
public interface Param {
    
    /**
     * get name of the parameter
     * @return name of the parameter
     */
    public String getParamName();
    
    /**
     * Converter for this parameter. Converter provide check and if it is necessary 
     * conversion of the value of parameter
     * @return return Converter for this parameter
     */
    public Converter getConverter();
    
    /**
     * get converted and checked value
     * @return converted and checked value
     */
    public String getValue();
    
    /**
     * set value for this parameter. Value will be checked and converted with 
     * {@link sk.lieskove.jianghongtiao.aresapi.webservice.converters.Converter}
     * of the class.
     * @param value value to set
     * @throws Exception in case that value does not pass converter tests
     */
    public void setValue(String value) throws Exception;
    
    /**
     * return as parameter for URL. it means in format &lt;param&gt; = &lt;value&gt;
     * but value have to be URL-encoded with given encoding
     * @param encoding 
     * @return name and value in URL format. Value is URL encoded with given encoding
     */
    public String asUrlParam(String encoding) throws UnsupportedEncodingException;
    
}
